iCaLViewer 1.0.2
25 April, 2003
Copyright (c) 2003 Karl Goiser.  All rights reserved.

Author and original idea: Karl Goiser.

Preface
When your screen saver kicks in, you have the choice of wild and wonderful graphics of every sort or a plain old boring blank screen.  How about something really useful as an alternative?  What if you could display your upcoming events and appointments in a pleasing and informative manner?

Enter iCalViewer!

Description
iCalViewer displays the events from Apple's calendar application, iCal, in a window.  Each event is displayed in a similar way to iCal and marches towards a finish line which is the time now.

But wait!  There's more!  iCalViewer also comes as a handy screen saver, iCalSaver!

Although you cannot, at present, interact with individual events, there are options which allow altering the overall display in the preferences dialogue and the 'Window' menu.

Features:
	• Comes as an application or screen saver
	• Simple design
	• Similar look to iCal
	• nifty display modes
	• easy to use
	• more to come!

Windows
iCalViewer only every displays one window, but has four ways of displaying it.

• Normally it will display the usual type of resizable window that can be seen in many applications.

The other ways are based around full-screen windows:

• 'Saver' mode (command-F) displays a full-screen window with a black background just like most screen savers.

• Full Screen Transparent (command-T) is like the above, but the window background is transparent so the normal desktop view is visible behind the events.  This is live, so work can be carried out while the events slide slowly over the screen!

• On the desktop (command-D) is like the transparent mode, but the events are displayed behind everything and above the desktop picture.

These modes are available via the 'Window' menu or through their keyboard equivalents while the application is active.  To make it active, just click on an event or the icon in the Dock.

Preferences:
Hours lookahead
Specifies how many hours in the future to display (may be between 1 and 1000).

For example, entering 24 will display a complete day's events from the left hand edge of the display to the finish line.  240 will display all the events coming up for the next 10 days.

Currently, the time to the right of the finish line (i.e. the past) is set at 10% of the time on its left.

Seconds per update:
How many seconds between each update  (may be between 1 and 10000).

Updates affect the following: event position, dynamic time displays and the addition of new events.

Width proportional to duration
Normally, the width of an event is determined by how wide the time display information is.  However, checking this checkbox makes the width of the boxes proportional to the duration of the event.

For example, if you are displaying 3 hours ahead and there is an event on the display that lasts for one hour, its displayed width will be one third of the distance between the left hand edge of the display and the 'finish' line.

The minimum width of an event is 10 pixels, which doesn't display any information.  However, its distance from the finish line does provide an indication of how far away that event is.

Show relative times
If selected, each event will display the amount of time between now and the start of the event in hours:minutes:seconds format.

*** Change in 1.0.2:
The relative time display is now relative and more relevant:

The units displayed are
	weeks, days
	days, hours
	hours, minutes
	minutes, seconds
whichever is relevant
***

When the event has already started, it will display the amount of time since started, and if it has completed, it will display the amount of time since the end of the event.

Show date
This checkbox allows display of the actual time and date of the event.

Alpha
This slider allows specification of the transparency of the objects on the display.

With the knob fully to the right, the objects will be fully solid;  fully to the left and the objects will be fully transparent (i.e. invisible).

Allowing transparency can be a pleasing effect when viewing many overlapping events.

Contact:
I can be contacted via email at kgg@mac.com.

I welcome comments, both positive and negative as well as suggestions and bug reports.  However, if you send a negative comment, you should provide a solution as well.

License
You are free to use and copy the application.  You are not allowed to modify the application without obtaining my consent.

Use of the application is on an 'all care but no responsibility' basis.  That is, I am doing my best to provide accurate information, but if I make a mistake, I am under no responsibility to correct or redress it or its consequences.  Don't use or rely on the information provided if you don't like this.

Credits:
Two methods are from the Anguish et al book and some code derives from the Cheeseman book, otherwise all code is my own.

I would like to thank the following people.  This application would never have been released without them!

Anguish, Buck and Yacktman for their "Cocoa Programming" book.  Not only is it a great reference, but it supplied the rounded rectangle and colour blending source code.

Bill Cheeseman for his "Cocoa Recipes for Mac OS X" book.  Specifically for its attention to the details of completing an application.

The helpful people on the Cocoa-Dev list where I occasionally lurk.

The people at Apple Computer for providing such a great development environment (how's the incremental compiling coming along guys?).

My family! for allowing me the time to complete it.

The University of Tasmania, Australia where I study, for giving me the drive to take this idea to completion.

I would also like to acknowledge the Apple University Consortium (Australia) (http://auc.uow.edu.au/) who were kind enough to select me to be among a group of 16 scholarship winners for studentships to WWDC 2002.  Attending opened my eyes to the wide world of Apple and to the excitement of its developers!

Known Bugs
- The test button in the screen saver doesn't work as expected - you get the finish line, but no events.  The screen saver does otherwise work.

- The preview view of the screen saver displays the events objects in full size.  I need to make them appear proportional to the screen size...

Version information:
1.0.2 - Bug fix release.
25/4/2003
Bug fixes and change:

Fixed:
- previous versions would ignore the 'every x weeks' setting in the repetition rules,
- the alpha setting now also affects the 'finish line',
- display of '\' characters in the event title,
- width setting in the screen saver.

Changed:
- pressing the 'esc' key now quits the full screen mode in the viewer application,
- titles are now more visible with emerging events,
- time to go to display now uses more relevant units.

1.0.1 - Bug fix release.
20/4/2003
This release only contains bug fixes, several of which were brought to my attention by feedback from kind people.  Thank you!

- International text should now display properly.
- Events on the desktop no longer 'cover' desktop icons.
- Addressed some problems with the configuration panel of the screen saver and preferences.
- Various smaller fixes
- Some speed-ups.  More to come...

1.0 - First release.

Future Directions:
I plan to implement the following in future versions:

• Mousing over an event will display more information about that event

• Also display todo's

Specific programming details to do:
• Unify the application and screen saver's preferences.
• Fix up the configuration sheet of the screen saver.
• Progress indicator when reading the calendars in.
• The ability to print a screen.
• Smarter layering of the events (newest on top?).
• Flash the screen when events are coming up?

Vague Possibilities:
• Look at some effects - e.g. how alarms might be addressed.
• Have no finish line
• Other directions of travel:
	- from the top
	- to the left
	- coming at you!

• allow selecting calendars